Tra cứu lệnh chuyển đổi

Tra cứu trạng thái và chi tiết một lệnh chuyển đổi. API hỗ trợ hai mục đích:

Timeout recovery — khi gọi Thực thi chuyển đổi bị timeout, tra cứu kết quả lệnh mà không cần retry
Đối soát — tra cứu lệnh trong ngày phục vụ reconcile

Hỗ trợ hai cách tra cứu

Theo conversion_id — nếu Merchant đã nhận được conversion_id trong response Thực thi chuyển đổi
Theo origin_request_id — nếu Merchant chưa nhận response Thực thi chuyển đổi (timeout): dùng request_id của lệnh Thực thi chuyển đổi để tra

Trường hợp timeout chưa nhận conversion_id, tra theo origin_request_id. Nếu nhận mã 430 (không tìm thấy), lệnh gốc chưa được ghi nhận phía Baokim, Merchant an toàn để retry Thực thi chuyển đổi với cùng request_id.

Luồng xử lý

Đường dẫn

URL: /api/v1/fx/conversion-detail
Method: POST

Request

Tham số	Loại dữ liệu	Bắt buộc	Mô tả
request_id	string(50)	Có	Mã duy nhất định danh request (của chính lệnh tra cứu này). Xem mục 3 Giới thiệu
request_time	string(19)	Có	Xem mục 3 Giới thiệu
merchant_code	string(20)	Có	Xem mục 3 Giới thiệu
conversion_id	string(50)	Có điều kiện	Mã lệnh chuyển đổi cần tra cứu. Bắt buộc nếu không truyền `origin_request_id`.
origin_request_id	string(50)	Có điều kiện	`request_id` của lệnh Thực thi chuyển đổi cần tra cứu. Bắt buộc nếu không truyền `conversion_id`. Truyền cả hai → ưu tiên `conversion_id`.

Ví dụ Request — tra theo conversion_id

{
  "request_id": "MERCHANT1234BK202606050003",
  "request_time": "2026-06-05 10:16:10",
  "merchant_code": "MERCHANT1234",
  "conversion_id": "FXC202606051015450001"
}

Ví dụ Request — tra theo origin_request_id (timeout recovery)

{
  "request_id": "MERCHANT1234BK202606050003",
  "request_time": "2026-06-05 10:16:10",
  "merchant_code": "MERCHANT1234",
  "origin_request_id": "MERCHANT1234BK202606050002"
}

Response

Tham số	Loại dữ liệu	Bắt buộc	Mô tả
response_code	int(4)	Có	Mã kết quả
response_message	string(200)	Có	Mô tả mã kết quả
merchant_code	string(20)	Có	Mã merchant
data	Object	Có	Chi tiết lệnh chuyển đổi (cấu trúc giống response Thực thi chuyển đổi)

Cấu trúc `data`

Cấu trúc data giống response của Thực thi chuyển đổi:

Tham số	Loại dữ liệu	Mô tả
conversion_id	string(50)	Mã lệnh chuyển đổi
origin_request_id	string(50)	`request_id` của lệnh gốc
status	string(20)	Trạng thái lệnh: `PROCESSING`, `SUCCESS`, `FAILED`
quote_id	string(50)	Mã báo giá đã thực thi
trade_type	string(4)	Loại hình giao dịch (SELL/BUY)
currency_pair	string(10)	Cặp tiền tệ chuẩn hóa
rate	decimal(18,4)	Tỷ giá đã thực thi
from_currency	string(3)	Đồng tiền nguồn
from_amount	decimal(18,2)	Số tiền nguồn đã trừ
to_currency	string(3)	Đồng tiền đích
to_amount	decimal(18,2)	Số tiền đích đã ghi có
created_at	string(19)	Thời điểm tạo lệnh
completed_at	string(19)	Thời điểm hoàn tất. Null khi `status = PROCESSING`.

Ví dụ Response

{
  "response_code": 200,
  "response_message": "Success",
  "merchant_code": "MERCHANT1234",
  "data": {
    "conversion_id": "FXC202606051015450001",
    "origin_request_id": "MERCHANT1234BK202606050002",
    "status": "SUCCESS",
    "quote_id": "FXQ0605A7K2M9XD41",
    "trade_type": "SELL",
    "currency_pair": "USD/VND",
    "rate": 26450.0000,
    "from_currency": "USD",
    "from_amount": 10000.00,
    "to_currency": "VND",
    "to_amount": 264500000,
    "created_at": "2026-06-05 10:15:45",
    "completed_at": "2026-06-05 10:15:46"
  }
}

Mã lỗi

Mã Response	Thông báo Response	Mô tả
200	Success
101	System Error	Lỗi không mong muốn phía Baokim
110	Merchant code invalid	`merchant_code` không xác định
120	Invalid signature	Header `Signature` không hợp lệ
422	Validation Error	Thiếu cả `conversion_id` và `origin_request_id`, hoặc trường khác không hợp lệ
429	Too many requests	Vượt quá giới hạn tỷ lệ cho Merchant
430	Conversion not found	Không tìm thấy lệnh với `conversion_id` hoặc `origin_request_id`. Nếu tra theo `origin_request_id`: lệnh gốc chưa được ghi nhận, Merchant an toàn để retry Thực thi chuyển đổi.

Hỗ trợ hai cách tra cứu​

Luồng xử lý​

Đường dẫn​

Request​

Ví dụ Request — tra theo conversion_id​

Ví dụ Request — tra theo origin_request_id (timeout recovery)​

Response​

Cấu trúc data​

Ví dụ Response​

Mã lỗi​